/**
 * Copyright (c) 2006-2012 Las Venturas Playground, LVP Mineground
 *
 * This program is free software: you can redistribute it and/or modify it under the terms of the
 * GNU General Public License as published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
 * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

package mineground.entities;

import mineground.entities.requests.LocationRunnable;

/**
 * The Player interface describes how the Mineground layer is able to communicate with players. The
 * actual implementation is responsible for managing thread-safety where required, making sure that
 * this is not something game modules have to think about.
 * 
 * The Player object will be passed around through several messages. The objects can be retained
 * after a player disconnects, but keep in mind that this will also block Java's garbage collection
 * procedures from removing it.
 */
public interface Player {
    /**
     * Retrieve the name of this player.
     * 
     * @return String The username of the player.
     */
    public abstract String getName();
    
    /**
     * Retrieve the display name used by this player. This may be different from their nickname, and
     * should be used for the chat box.
     * 
     * @return String The display name of the player, used in chat.
     */
    public abstract String getDisplayName();
    
    /**
     * Request the current location of the entity and execute the callback once it's known.
     * 
     * @param callback The Location Runnable which should be executed.
     */
    public abstract void requestLocation(LocationRunnable callback);
    
    /**
     * Distribute a message to the user, which is to be displayed in their chat box.
     * 
     * @param message The message which should be send to the user.
     */
    public void sendMessage(String message);
}
